Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / Shape Objects Reference

Functions / Creating and Manipulating Shape Objects

GXCloneShape

You can use the GXCloneShape function to clone a shape--that is, to add a reference to it and increment its owner count.

gxShape GXCloneShape(gxShape source);

source

A reference to the shape to clone.

function result

A reference to the cloned shape.

DESCRIPTION

The GXCloneShape function returns a reference to the shape object specified by the source parameter and increments its owner count by 1. You typically use this function when you want to create another reference to an existing shape rather than create a distinct copy of the shape.

This function returns as its function result a reference to the shape--the same reference you pass in as the source parameter. Thus you can clone a shape with the following line of C code:

aShapeClone = GXCloneShape(aShape);

This line of code has almost the same affect as

aShapeClone = aShape;

that is, it sets the aShapeClone variable to reference the same shape object as the aShape variable. The difference is that GXCloneShape also increments the shape's owner count.

ERRORS, WARNINGS, AND NOTICES

Errors
shape_is_nil

SEE ALSO

Owner counts are discussed in the section "Copying, Comparing, and Cloning Shape Objects" beginning on page 2-25, and in the section "Manipulating a Shape Object's Owner Count" beginning on page 2-31.

To examine the owner count of a shape, use the GXGetShapeOwners function, described on page 2-76. To decrement the owner count of a shape, use the GXDisposeShape function, described on page 2-55.